home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 26.zip / BS1 part 26 / Powervisor v1.10b disk2.adf / Debug < prev    next >
Text File  |  1991-09-22  |  46KB  |  1,044 lines
  1. *-----------------*
  2. * Tutorial: Debug * Sun Sep 22 13:19:20 1991
  3. *-----------------*
  4.  
  5. ===================== Commands used in this tutorial =========================
  6.  
  7.    break       Control breakpoints
  8.    debug       Control debug tasks
  9.    disp        Display integer
  10.    drefresh    Refresh debug display
  11.    dscroll     Scroll in debug display
  12.    dstart      Set start programcounter in debug display
  13.    duse        Set the default debug task
  14.    dwin        Open/close 'Debug' logical window
  15.    info        Ask information about a structure or node
  16.    list        List structures
  17.    loadfd      Load fd-file
  18.    prefs       Set preferences
  19.    symbol      Control symbols
  20.    trace       Control tracing
  21.    unasm       Disassemble memory
  22.    with        Temporarily set the default debug task
  23.  
  24.  
  25. ===================== Functions used in this tutorial ========================
  26.  
  27.    botpc       Get the programcounter at the bottom of the display
  28.    toppc       Get the programcounter at the top of the display
  29.  
  30.  
  31. ============================== Introduction ==================================
  32.  
  33. I don't think that you will be surprised if I tell you that PowerVisor can
  34. even debug programs :-) This file explains how you should do this. It also
  35. explains how you can make life easier with a fully customized
  36. ²fullscreen debugger. PowerVisor is a very powerful debugger. For example,
  37. you can ³debug multiple tasks at the same time.
  38.  
  39.  
  40. ============================ Loading a program ===============================
  41.  
  42. There are several ways to load a program. The method you chooses depends on
  43. what you really need. The 'debug' command is provided by PowerVisor to
  44. control the ²debug tasks (or debug nodes). All the ²debug nodes can be found
  45. in the ²'dbug' list. With the 'debug' command you can load a program, you can
  46. unload a program and you can do other things as well.
  47.  
  48.  
  49. =========================== An example session ===============================
  50.  
  51. This section contains a complete example debugging session. Note that we
  52. do not use the ²fullscreen debugger in this example. Use of the fullscreen
  53. debugger is explained later. It is recommended that you type each command
  54. as it appears here. Note that the output given here assumes that you have
  55. all preferences set to default values (use 'mode shex', 'prefs dmode f' and
  56. 'prefs debug 5 1' if you are not sure that the default values are used).
  57.  
  58.  
  59. -------------------------- Starting the session ------------------------------
  60.  
  61. 'debug n' is the recommended way to load a program. 'debug n' waits for
  62. the next program that is started and interrupts it before the first
  63. instruction is executed. To do this, 'debug n' patches the Dos ¹LoadSeg
  64. function. Example :
  65.  
  66. < debug n <enter>
  67.  
  68. PowerVisor waits for you to start the program you want to debug. You
  69. can start this program from the ¹WorkBench (click on the icon) or you
  70. can start it from the Cli or Shell. I have provided an example program
  71. with a ²resident breakpoint. Resident breakpoints are explained later
  72. in this file. You can find this program in the ²'Examples' subdirectory.
  73.  
  74. CLI< examples/buggyprogram <enter>
  75. or
  76. CLI< run examples/buggyprogram <enter>
  77.  
  78. (Note ! Only use 'run' when 'run' is ¹resident or a built-in shell command,
  79. in other words: don't use 'run' when 'run' itself must be loaded from disk
  80. with 'loadseg'. You probably don't want to debug 'run' :-) 'run' is always
  81. resident in AmigaDOS 2.0)
  82.  
  83. (Note ! When PowerVisor is waiting for a program you must be careful not
  84. to use any other program (that is already running) that might use LoadSeg
  85. for some other purpose. Fonts, for example, are loaded using LoadSeg)
  86.  
  87. (Note ! You can ¹interrupt 'debug n' with ¹<esc>)
  88.  
  89. 'debug n' is the best way to load a debug task because the program runs
  90. in exactly the same environment as the environment you get when you simply
  91. run the program.
  92.  
  93. Allright, we have now loaded the program in memory.
  94.  
  95. < list dbug <enter>
  96. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  97. > ---------------------------------------------------------------------------
  98. > Background CLI      : 07EA7A58 07EF8FA8 07EAA7D8 FF FF NONE  WAIT  NORM
  99.  
  100. Most of this information is rather technical and is not very interesting at
  101. this moment. 'InitPC' is interesting though. Let's try :
  102.  
  103. < u 07EAA7D8 <enter>
  104. or
  105. < unasm 07EAA7D8 <enter>
  106.  
  107. > 07EAA7D8: 7200                          MOVEQ.L  #0,D1
  108. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  109. > 07EAA7DC: 5281                          ADDQ.L   #1,D1
  110. > 07EAA7DE: 51C8 FFFC                     DBF      D0,$7EAA7DC
  111. > 07EAA7E2: 6100 0010                     BSR      $7EAA7F4
  112. > 07EAA7E6: 6708                          BEQ      $7EAA7F0
  113. > 07EAA7E8: 6100 0022                     BSR      $7EAA80C
  114. > 07EAA7EC: 6100 0046                     BSR      $7EAA834
  115. > 07EAA7F0: 7000                          MOVEQ.L  #0,D0
  116. > 07EAA7F2: 4E75                          RTS
  117. > 07EAA7F4: 203C 0000 0064                MOVE.L   #$64,D0
  118. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  119. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  120. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  121. > 07EAA804: 41FA 0042                     LEA      ($7EAA848,PC),A0
  122. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  123. > 07EAA80A: 4E75                          RTS
  124. > 07EAA80C: 7000                          MOVEQ.L  #0,D0
  125. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  126. > 07EAA810: 7402                          MOVEQ.L  #2,D2
  127.  
  128. Well, this is our program. But there are ²symbol hunks in our program.
  129. 'debug n' does not automatically load them ('debug l' does, but this command
  130. will be explained later). You can ²load symbols with the 'symbol' command :
  131.  
  132. < symbol l examples/buggyprogram <enter>
  133.  
  134. < u 07EAA7D8 <enter>
  135. > StartProgr7200                          MOVEQ.L  #0,D1
  136. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  137. > loop      5281                          ADDQ.L   #1,D1
  138. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  139. > 07EAA7E2: 6100 0010                     BSR      Sub1
  140. > 07EAA7E6: 6708                          BEQ      theend
  141. > 07EAA7E8: 6100 0022                     BSR      Sub2
  142. > 07EAA7EC: 6100 0046                     BSR      Sub3
  143. > theend    7000                          MOVEQ.L  #0,D0
  144. > 07EAA7F2: 4E75                          RTS
  145. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  146. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  147. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  148. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  149. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  150. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  151. > 07EAA80A: 4E75                          RTS
  152. > Sub2      7000                          MOVEQ.L  #0,D0
  153. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  154. > 07EAA810: 7402                          MOVEQ.L  #2,D2
  155.  
  156. You can ³show all symbols with the 'symbol' command :
  157.  
  158. < symbol s <enter>
  159. > StartProgram                             : 07EAA7D8 , 132818904
  160. > loop                                     : 07EAA7DC , 132818908
  161. > theend                                   : 07EAA7F0 , 132818928
  162. > Sub1                                     : 07EAA7F4 , 132818932
  163. > Sub2                                     : 07EAA80C , 132818956
  164. > Sub3                                     : 07EAA834 , 132818996
  165. > Block                                    : 07EAA848 , 132819016
  166.  
  167. The two values on the right of each symbol are the same. The only difference
  168. is that the left one is ¹hexadecimal and the right one is ¹decimal.
  169.  
  170. Because we have loaded the symbols for the current debug task we can use the
  171. symbols in ¹expressions. Here are some examples :
  172.  
  173. Disassemble 5 instructions starting with 'StartProgram' (note that symbols
  174. are case sensitive) :
  175.  
  176. < u StartProgram 5 <enter>
  177. > StartProgr7200                          MOVEQ.L  #0,D1
  178. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  179. > loop      5281                          ADDQ.L   #1,D1
  180. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  181. > 07EAA7E2: 6100 0010                     BSR      Sub1
  182.  
  183. Show the distance between subroutine 2 and subroutine 1 :
  184.  
  185. < d Sub2-Sub1 <enter>
  186. > 00000018,24
  187.  
  188. You can do many other things with the 'symbol' command but 'symbol l' and
  189. 'symbol s' are sufficient at this moment.
  190.  
  191. There is still one thing we should do :
  192.  
  193. < loadfd exec fd:exec_lib.fd <enter>
  194.  
  195. With this command PowerVisor loads all the ³library function definitions in
  196. memory. That way PowerVisor will know how to show a ²library function when
  197. one is encountered while ¹tracing. You do not have to load ¹fd-files, but
  198. it is certainly very easy. I have the four big fd-files ('exec.library',
  199. 'graphics.library', 'intuition.library' and 'dos.library') permanently
  200. loaded in memory (I have put four 'loadfd' commands in the
  201. ¹s:PowerVisor-startup file).
  202.  
  203.  
  204. ----------------------------------Tracing ------------------------------------
  205.  
  206. Now we can start tracing :
  207.  
  208. < trace i <enter>
  209. or
  210. < tr i <enter>
  211. > ---------------------------------------------------------------------------
  212. > D0: 00000001   D1: 01FAA9F5   D2: 00002EE0   D3: 07ED3A1C
  213. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  214. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  215. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  216. > PC: 07EAA7D8   SP: 07EFCBFC   SR: 0010
  217. > 00000000: 0000 0000                     ORI.B    #0,D0
  218. >
  219. > StartProgr7200                          MOVEQ.L  #0,D1
  220. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  221. > loop      5281                          ADDQ.L   #1,D1
  222. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  223. > 07EAA7E2: 6100 0010                     BSR      Sub1
  224.  
  225. (tr i : give 'I'nformation)
  226. This command shows where we are. No actual tracing is done. The registers
  227. are shown and the five first instructions. The program counter points to the
  228. second instruction in this output. The first instruction is always equal to
  229. the previous executed instruction. Initially it is initialized to address 0.
  230. Note that you can change the format of this output with the 'prefs dmode'
  231. and 'prefs debug' commands (See the 'InstallingPowerVisor' file).
  232.  
  233. Now we are really going to trace one instruction :
  234.  
  235. < tr <enter>
  236. > ---------------------------------------------------------------------------
  237. > D0: 00000001   D1: 00000000   D2: 00002EE0   D3: 07ED3A1C
  238. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  239. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  240. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  241. > PC: 07EAA7DA   SP: 07EFCBFC   SR: 0014
  242. > StartProgr7200                          MOVEQ.L  #0,D1
  243. >
  244. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  245. > loop      5281                          ADDQ.L   #1,D1
  246. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  247. > 07EAA7E2: 6100 0010                     BSR      Sub1
  248. > 07EAA7E6: 6708                          BEQ      theend
  249.  
  250. In the register display you can see that 'd1' now has the value 0.
  251. 'StartProgr' is now the previous instruction. The programcounter now points
  252. to the instruction 'moveq.l #$64,d0'.
  253.  
  254. Trace six instructions at once :
  255.  
  256. < tr n 6 <enter>
  257. > ---------------------------------------------------------------------------
  258. > D0: 00000062   D1: 00000003   D2: 00002EE0   D3: 07ED3A1C
  259. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  260. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  261. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  262. > PC: 07EAA7DE   SP: 07EFCBFC   SR: 0000
  263. > loop      5281                          ADDQ.L   #1,D1
  264. >
  265. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  266. > 07EAA7E2: 6100 0010                     BSR      Sub1
  267. > 07EAA7E6: 6708                          BEQ      theend
  268. > 07EAA7E8: 6100 0022                     BSR      Sub2
  269. > 07EAA7EC: 6100 0046                     BSR      Sub3
  270.  
  271. (tr n : trace 'N'umber instruction)
  272. We are now in the loop.
  273.  
  274. To ²step over the loop we can use the following instruction :
  275.  
  276. < tr o <enter>
  277. > ---------------------------------------------------------------------------
  278. > D0: 0000FFFF   D1: 00000065   D2: 00002EE0   D3: 07ED3A1C
  279. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  280. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  281. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  282. > PC: 07EAA7E2   SP: 07EFCBFC   SR: 0000
  283. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  284. >
  285. > 07EAA7E2: 6100 0010                     BSR      Sub1
  286. > 07EAA7E6: 6708                          BEQ      theend
  287. > 07EAA7E8: 6100 0022                     BSR      Sub2
  288. > 07EAA7EC: 6100 0046                     BSR      Sub3
  289. > theend    7000                          MOVEQ.L  #0,D0
  290. > Breakpoint...
  291.  
  292. (tr o : trace 'O'ver)
  293. 'tr o' places a ¹breakpoint after the current instruction and then executes
  294. until the breakpoint is encountered. You can trace over every instruction
  295. with this command, but you can't use it in ¹ROM-code since PowerVisor can't
  296. put a ³breakpoint in ROM (don't worry ! there are solutions to this problem,
  297. we will see them later on).
  298.  
  299. We step into the subroutine 'Sub1' with :
  300.  
  301. < tr <enter>
  302. > ---------------------------------------------------------------------------
  303. > D0: 0000FFFF   D1: 00000065   D2: 00002EE0   D3: 07ED3A1C
  304. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  305. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  306. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  307. > PC: 07EAA7F4   SP: 07EFCBF8   SR: 0000
  308. > 07EAA7E2: 6100 0010                     BSR      Sub1
  309. >
  310. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  311. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  312. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  313. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  314. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  315.  
  316. Trace another three instructions :
  317.  
  318. < tr n 3 <enter>
  319. > ---------------------------------------------------------------------------
  320. > D0: 00000064   D1: 00000000   D2: 00002EE0   D3: 07ED3A1C
  321. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  322. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  323. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  324. > PC: 07EAA800   SP: 07EFCBF8   SR: 0004
  325. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  326. >
  327. > 07EAA800: 4EAE FF3A                     JSR      (AllocMem,A6)
  328. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  329. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  330. > 07EAA80A: 4E75                          RTS
  331. > Sub2      7000                          MOVEQ.L  #0,D0
  332.  
  333. Thanks to the loaded fd-file you can now see that this function is actually
  334. the Exec AllocMem. We do not want to run through the complete rom function
  335. so we ²trace over the call with :
  336.  
  337. < tr t <enter>
  338. > ---------------------------------------------------------------------------
  339. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  340. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  341. > A0: 07E00000   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  342. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  343. > PC: 07EAA804   SP: 07EFCBF8   SR: 0010
  344. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  345. >
  346. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  347. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  348. > 07EAA80A: 4E75                          RTS
  349. > Sub2      7000                          MOVEQ.L  #0,D0
  350. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  351. > Breakpoint...
  352.  
  353. (tr t : 'T'race over BSR or JSR      sorry, couldn't find a better character)
  354. 'tr t' looks similar to 'tr o'. The big difference is that 'tr t' works only
  355. for 'BSR' and 'JSR' instructions. And what is more important : 'tr t' works
  356. in ¹ROM-code. If 'tr t' is used for an instruction other than 'BSR' or 'JSR'
  357. it is analogous to 'tr' (simple singlestep).
  358.  
  359. We can see that the AllocMem function had success (I hope this is really the
  360. case) because 'd0' contains the address of the newly allocated memory.
  361.  
  362. We continue tracing until the next ³change of program flow happens :
  363.  
  364. < tr b <enter>
  365. > ---------------------------------------------------------------------------
  366. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  367. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  368. > A0: 07EAA848   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  369. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  370. > PC: 07EAA80A   SP: 07EFCBF8   SR: 0010
  371. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  372. >
  373. > 07EAA80A: 4E75                          RTS
  374. > Sub2      7000                          MOVEQ.L  #0,D0
  375. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  376. > 07EAA810: 7402                          MOVEQ.L  #2,D2
  377. > 07EAA812: 7603                          MOVEQ.L  #3,D3
  378.  
  379. (tr b : trace until 'B'ranch)
  380. 'tr b' traces until a change of program control happens. This means that
  381. tracing will stop always at the following instructions :
  382.    JMP
  383.    JSR
  384.    BRA
  385.    BSR
  386.    RTE
  387.    RTD
  388.    RTR
  389.    RTS
  390.    TRAP
  391. and tracing will stop at the following instructions if the brach would
  392. succeed :
  393.    Bcc
  394.    DBcc
  395.  
  396. Go out this subroutine :
  397.  
  398. < tr <enter>
  399. > ---------------------------------------------------------------------------
  400. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  401. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  402. > A0: 07EAA848   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  403. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  404. > PC: 07EAA7E6   SP: 07EFCBFC   SR: 0010
  405. > 07EAA80A: 4E75                          RTS
  406. >
  407. > 07EAA7E6: 6708                          BEQ      theend
  408. > 07EAA7E8: 6100 0022                     BSR      Sub2
  409. > 07EAA7EC: 6100 0046                     BSR      Sub3
  410. > theend    7000                          MOVEQ.L  #0,D0
  411. > 07EAA7F2: 4E75                          RTS
  412.  
  413. < tr <enter>
  414. > ---------------------------------------------------------------------------
  415. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  416. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  417. > A0: 07EAA848   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  418. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  419. > PC: 07EAA7E8   SP: 07EFCBFC   SR: 0010
  420. > 07EAA7E6: 6708                          BEQ      theend
  421. >
  422. > 07EAA7E8: 6100 0022                     BSR      Sub2
  423. > 07EAA7EC: 6100 0046                     BSR      Sub3
  424. > theend    7000                          MOVEQ.L  #0,D0
  425. > 07EAA7F2: 4E75                          RTS
  426. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  427.  
  428. We suspect nothing bad in 'Sub2' so we simply trace over it :
  429.  
  430. < tr t <enter>
  431. > ---------------------------------------------------------------------------
  432. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  433. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  434. > A0: 07EFCE90   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  435. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  436. > PC: 07EAA820   SP: 07EFCBF8   SR: 0010
  437. > 07EAA7E8: 6100 0022                     BSR      Sub2
  438. >
  439. > 07EAA820: 4AFC                          ILLEGAL
  440. > 07EAA822: 20C0                          MOVE.L   D0,(A0)+
  441. > 07EAA824: 20C1                          MOVE.L   D1,(A0)+
  442. > 07EAA826: 20C2                          MOVE.L   D2,(A0)+
  443. > 07EAA828: 20C3                          MOVE.L   D3,(A0)+
  444. > Illegal instruction !
  445.  
  446. There is something wrong ! This is called a ²²resident breakpoint. You can
  447. put resident breakpoints in a program using the ²'ILLEGAL' instruction.
  448. PowerVisor will automatically stop at such places.
  449.  
  450. ²Skip over the instruction with :
  451.  
  452. < tr s <enter>
  453. > ---------------------------------------------------------------------------
  454. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  455. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  456. > A0: 07EFCE90   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  457. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  458. > PC: 07EAA820   SP: 07EFCBF8   SR: 0010
  459. > 07EAA820: 4AFC                          ILLEGAL
  460. >
  461. > 07EAA822: 20C0                          MOVE.L   D0,(A0)+
  462. > 07EAA824: 20C1                          MOVE.L   D1,(A0)+
  463. > 07EAA826: 20C2                          MOVE.L   D2,(A0)+
  464. > 07EAA828: 20C3                          MOVE.L   D3,(A0)+
  465. > 07EAA82A: 20C4                          MOVE.L   D4,(A0)+
  466.  
  467. ('tr s' : 'S'kip instruction)
  468. Now we have something special. Since we used the 'tr t' command to trace
  469. over the subroutine 'Sub2' we have created a breakpoint after the 'BSR Sub2'
  470. instruction. But if we would look after the 'BSR Sub2' instruction we
  471. would find no breakpoint (we will see later how PowerVisor shows breakpoints
  472. in the disassembly display). This is because the 'tr t' command works in
  473. a special way to make sure that you can use it in ROM-code too. Here follows
  474. an explanation of what has happened :
  475.  
  476.       You typed 'tr t' when to skip 'BSR Sub2' a time ago.
  477.       PowerVisor performs a 'tr' to trace the 'BSR' instruction.
  478.       Now the top of the stack contains the returnaddress for the 'BSR'
  479.       instruction, this is the address of the instruction after 'BSR Sub2'.
  480.       PowerVisor replaces the address on the stack with another address.
  481.       This address points to a ²private breakpoint. Since this private
  482.       breakpoint is always in RAM, there is no problem setting this
  483.       breakpoint. When the subroutine returns (with 'RTS') later on (this
  484.       has not happened at this moment), it will not return to the instruction
  485.       after the 'BSR' but to the breakpoint in RAM. PowerVisor will trap this
  486.       and set the programcounter of the task to the right address: this is
  487.       the instruction after the 'BSR Sub2'.
  488.  
  489.       It would be different if you hade used 'tr o' instead of 'tr t'. 'tr o'
  490.       would put a breakpoint directly after the 'BSR Sub2'. This will
  491.       ofcourse not work if the 'BSR' is in ROM since a breakpoint is in fact
  492.       an ILLEGAL instruction.
  493.  
  494. But since the routine 'Sub2' was interrupted (the 'ILLEGAL' instruction
  495. caused this). The private breakpoint has not been encountered yet and
  496. the value on the stack is still the wrong value. We can make use of this
  497. feature and simply continue the 'tr t' where it left of with :
  498.  
  499. < tr g <enter>
  500. > ---------------------------------------------------------------------------
  501. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  502. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  503. > A0: 07EFCEB0   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  504. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  505. > PC: 07EAA7EC   SP: 07EFCBFC   SR: 0010
  506. > 07EAA822: 20C0                          MOVE.L   D0,(A0)+
  507. >
  508. > 07EAA7EC: 6100 0046                     BSR      Sub3
  509. > theend    7000                          MOVEQ.L  #0,D0
  510. > 07EAA7F2: 4E75                          RTS
  511. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  512. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  513. > Breakpoint...
  514.  
  515. ('tr g' : trace 'G'o)
  516. The 'tr g' command simply executes the program until a breakpoint is
  517. encountered.
  518. Note that it would make no difference if you would trace the program step
  519. by step. At one moment you would encounter the ²private breakpoint. Simply
  520. tracing over this breakpoint will return to the correct place in the
  521. program.
  522.  
  523. We step into 'Sub3' :
  524.  
  525. < tr <enter>
  526. > ---------------------------------------------------------------------------
  527. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  528. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  529. > A0: 07EFCEB0   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  530. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  531. > PC: 07EAA834   SP: 07EFCBF8   SR: 0010
  532. > 07EAA7EC: 6100 0046                     BSR      Sub3
  533. >
  534. > Sub3      203C 0000 0040                MOVE.L   #$40,D0
  535. > 07EAA83A: 227A 000C                     MOVEA.L  (Block,PC),A1
  536. > 07EAA83E: 2C78 0004                     MOVEA.L  (4),A6
  537. > 07EAA842: 4EAE FF2E                     JSR      ($FF2E,A6)
  538. > 07EAA846: 4E75                          RTS
  539.  
  540. < tr <enter>
  541. > ---------------------------------------------------------------------------
  542. > D0: 00000040   D1: 00000001   D2: 00000002   D3: 00000003
  543. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  544. > A0: 07EFCEB0   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  545. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  546. > PC: 07EAA83A   SP: 07EFCBF8   SR: 0010
  547. > Sub3      203C 0000 0040                MOVE.L   #$40,D0
  548. >
  549. > 07EAA83A: 227A 000C                     MOVEA.L  (Block,PC),A1
  550. > 07EAA83E: 2C78 0004                     MOVEA.L  (4),A6
  551. > 07EAA842: 4EAE FF2E                     JSR      ($FF2E,A6)
  552. > 07EAA846: 4E75                          RTS
  553. > Block     07EF CE90                     BSET     D3,($CE90,A7)
  554.  
  555. We see that something is wrong. We have allocated 100 bytes of memory
  556. ($64) but we are only going to free 64 bytes ($40). This is clearly
  557. a bug and should be fixed. But to prevent memoryloss we are going to
  558. continue anyway. We simply change the 'd0' ¹register :
  559.  
  560. < d @d0 <enter>
  561. > 00000040,64
  562.  
  563. < @d0=100 <enter>
  564.  
  565. You see how we can look at registers and change their values.
  566.  
  567. We are not interested in the rest of the program. We simply let it go :
  568.  
  569. < tr g <enter>
  570. > Program quits !
  571.  
  572. The program has stopped.
  573.  
  574. Some important 'trace' commands have been explained. There are a lot more.
  575. Some of the other 'trace' commands will be used in the following example.
  576. You have to refer to the online help or to the 'CommandReference' file for
  577. the other features.
  578.  
  579.  
  580. ============================ Example session 2 ===============================
  581.  
  582. I have prepared another program so you can see the power of PowerVisor.
  583. With this example we are going to make you used to breakpoints and some
  584. other advanced features of the 'trace' command. We are also going to use
  585. the ²²fullscreen debugger (Note that I will explain later how you can
  586. customize this fullscreen debugger to your wishes and how you can use
  587. the 'db' script to do this for you).
  588.  
  589.  
  590. -------------------------- Starting the session ------------------------------
  591.  
  592. We are now going to load the program using 'debug l'. Normally this is
  593. not the recommended way since this instruction does not perfectly emulate
  594. a ¹Cli or ¹WorkBench (this could change in future). But this does not matter
  595. for our little program.
  596.  
  597. < debug l examples/buggyprogram2 <enter>
  598.  
  599. The symbols are automatically loaded by 'debug l' :
  600.  
  601. < symbol s <enter>
  602. > StartProgram                             : 07EADCC0 , 132832448
  603. > Long                                     : 07EADCCE , 132832462
  604. > recur                                    : 07EADCE0 , 132832480
  605. > theend                                   : 07EADCEC , 132832492
  606.  
  607. Open the fullscreen debugger display :
  608.  
  609. < dwin <enter>
  610. < prefs dmode n <enter>
  611.  
  612. The 'prefs dmode' command is used to disable the output on the 'Main'
  613. logical window you normally get after each trace. All the output goes
  614. automatically to the 'Debug' logical window if it is open (but if you
  615. set 'prefs dmode f' as it is default you will get output in the 'Debug'
  616. logical window AND on the 'Main' logical window. This is probably not
  617. as intended).
  618.  
  619. Drag the ²horizontal bar between the ³'Main' logical window and the
  620. ³'Debug' logical window until all the five instructions of the disassembly
  621. are visible.
  622.  
  623. The following ¹keys can be used :
  624.       <ctrl>+<NumPad Up>      to decrease the top visible instruction address
  625.                               with 2
  626.       <ctrl>+<NumPad Down>    to increase this address with 2
  627.       <ctrl>+<NumPad PgUp>    to decrease this address with 20
  628.       <ctrl>+<NumPad PgDn>    to increase this address with 20
  629.       <ctrl>+<NumPad 5>       to set this address equal to the programcounter
  630. Using this keys you can ¹scroll through your code (try it).
  631.  
  632. Press :
  633.  
  634. < <ctrl>+<NumPad 5>
  635.  
  636. To go back to the programcounter.
  637. (Note that you can also use the 'dscroll' and 'dstart' commands to scroll
  638. through your program, see the 'CommandReference' file)
  639.  
  640. The fullscreen debugger display looks almost the same as the output from
  641. the 'trace' command in the earlier section. The differences are :
  642.  
  643.    - There is an indicator of what the task is doing.
  644.          NONE     the task is waiting for PowerVisor instructions
  645.          TRACE    the task is tracing
  646.          EXEC     the task is executing
  647.    - The top instruction (except for the previous instruction indicator)
  648.      is not always equal to the instruction at the ¹programcounter. The
  649.      programcounter is indicated by ²the vertical bar '|' in front of the
  650.      instruction.
  651.    - The ²previous instruction is only updated when the programcounter makes
  652.      a jump out of the current displayed instructions.
  653.  
  654.  
  655. ------------------------------- Breakpoints ----------------------------------
  656.  
  657. First a simple ¹¹breakpoint :
  658.  
  659. Lets put a breakpoint in the 'Long' subroutine.
  660.  
  661. < u Long <enter>
  662. > Long      7000                          MOVEQ.L  #0,D0
  663. > 07EADCD0: 7201                          MOVEQ.L  #1,D1
  664. > 07EADCD2: 7402                          MOVEQ.L  #2,D2
  665. > 07EADCD4: 7603                          MOVEQ.L  #3,D3
  666. > 07EADCD6: 7804                          MOVEQ.L  #4,D4
  667. > 07EADCD8: 7A05                          MOVEQ.L  #5,D5
  668. > 07EADCDA: 7C06                          MOVEQ.L  #6,D6
  669. > 07EADCDC: 7E07                          MOVEQ.L  #7,D7
  670. > 07EADCDE: 4E75                          RTS
  671. > recur     5280                          ADDQ.L   #1,D0
  672. > 07EADCE2: 0C80 0000 00C8                CMPI.L   #$C8,D0
  673. > 07EADCE8: 6E02                          BGT      theend
  674. > 07EADCEA: 61F4                          BSR      recur
  675. > theend    4E75                          RTS
  676. > 07EADCEE: 0000 07EA                     ORI.B    #$EA,D0
  677. > 07EADCF2: DD08                          ADDX.B   -(A0),-(A6)
  678. > 07EADCF4: 0000 0000                     ORI.B    #0,D0
  679. > 07EADCF8: 07E2                          BSET     D3,-(A2)
  680. > 07EADCFA: 68A0                          BVC      $7EADC9C
  681. > 07EADCFC: 0002 004C                     ORI.B    #$4C,D2
  682.  
  683. < break n 07EADCD2 <enter>
  684. or
  685. < b n 07EADCD2 <enter>
  686.  
  687. > 00000001,1
  688.  
  689. ('b n' : 'N'ormal breakpoint)
  690. The output from this command is the breakpoint number. PowerVisor can have
  691. as many breakpoints as memory permits. Breakpoints are always refered to
  692. with their number.
  693.  
  694. With the 'info' command you can now ask more information about the
  695. breakpoints :
  696.  
  697. < l dbug <enter>
  698. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  699. > ---------------------------------------------------------------------------
  700. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  NORM
  701.  
  702. < info dbug:'examples/buggyprogram2' dbug <enter>
  703. or
  704. < i db:examp db <enter>
  705.  
  706. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  707. > ---------------------------------------------------------------------------
  708. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  NORM
  709. >
  710. > Node     Number Where    UsageCnt Type Condition
  711. > ---------------------------------------------------------------------------
  712. > 07EBA168     1  07EADCD2        0   N
  713.  
  714. We can see that there is one breakpoint defined with number 1 and position
  715. 07EA77DA. It has not been used yet and it is a normal (N) breakpoint.
  716. ('Condition' is explained later).
  717.  
  718. Lets have a look at the disassembly :
  719.  
  720. < u Long 20 <enter>
  721. > Long      7000                          MOVEQ.L  #0,D0
  722. > 07EADCD0: 7201                          MOVEQ.L  #1,D1
  723. > 07EADCD2: 4AFC                          MOVEQ.L  #2,D2  >1
  724. > 07EADCD4: 7603                          MOVEQ.L  #3,D3
  725. > 07EADCD6: 7804                          MOVEQ.L  #4,D4
  726. > 07EADCD8: 7A05                          MOVEQ.L  #5,D5
  727. > 07EADCDA: 7C06                          MOVEQ.L  #6,D6
  728. > 07EADCDC: 7E07                          MOVEQ.L  #7,D7
  729. > 07EADCDE: 4E75                          RTS
  730. > recur     5280                          ADDQ.L   #1,D0
  731. > 07EADCE2: 0C80 0000 00C8                CMPI.L   #$C8,D0
  732. > 07EADCE8: 6E02                          BGT      theend
  733. > 07EADCEA: 61F4                          BSR      recur
  734. > theend    4E75                          RTS
  735. > 07EADCEE: 0000 07EA                     ORI.B    #$EA,D0
  736. > 07EADCF2: DD08                          ADDX.B   -(A0),-(A6)
  737. > 07EADCF4: 0000 0000                     ORI.B    #0,D0
  738. > 07EADCF8: 07E2                          BSET     D3,-(A2)
  739. > 07EADCFA: 68A0                          BVC      $7EADC9C
  740. > 07EADCFC: 0002 004C                     ORI.B    #$4C,D2
  741.  
  742. The breakpoint is the instruction with the '>1' appended.
  743.  
  744. Now we start the program and see where it ends :
  745.  
  746. < tr g <enter>
  747. > Breakpoint...
  748.  
  749. (Notice that we no longer get the complete output on 'Main'. All output
  750. is in the 'Debug' logical window)
  751.  
  752. The breakpoint has been encountered. Since it is a normal breakpoint it
  753. is not removed.
  754.  
  755. < i db:examp db <enter>
  756. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  757. > ---------------------------------------------------------------------------
  758. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  NORM
  759. >
  760. > Node     Number Where    UsageCnt Type Condition
  761. > ---------------------------------------------------------------------------
  762. > 07EBA168     1  07EADCD2        1   N
  763.  
  764. Now we see that the ²usage counter has incremented.
  765.  
  766. We make two new breakpoints :
  767.  
  768. < b t 07EADCDA <enter>
  769.  
  770. < b c recur @d0==100 <enter>
  771.  
  772. < i db:exam db <enter>
  773. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  774. > ---------------------------------------------------------------------------
  775. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  STEP
  776. >
  777. > Node     Number Where    UsageCnt Type Condition
  778. > ---------------------------------------------------------------------------
  779. > 07EBA288     3  07EADCE0        0   C  @d0==100
  780. > 07EB5B60     2  07EADCDA        0   T
  781. > 07EBA168     1  07EADCD2        1   N
  782.  
  783. ('b t' : 'T'emporary breakpoint)
  784. ('b c' : 'C'onditional breakpoint)
  785. 'b t' makes a ²temporary breakpoint. This is a breakpoint that only breaks
  786. once. 'b c' makes a conditional breakpoint. ²Conditional breakpoints are
  787. very powerful as you will see in the following demonstration.
  788.  
  789. < tr g <enter>
  790. > Breakpoint...
  791.  
  792. The breakpoint breaks and is immediatelly removed.
  793.  
  794. < tr g <enter>
  795. > Breakpoint...
  796.  
  797. The conditional breakpoint breaks because 'd0' is equal to 100. A conditional
  798. breakpoint is a very powerful way to control your program. The breakpoint
  799. condition can be as complex as you wish (with the exception that you can't
  800. use the ²group operator) and you can refer to all ¹registers like @sp, @d0 to
  801. @d7 and @a0 to @a6.
  802.  
  803. We ³remove the breakpoint with :
  804.  
  805. < b r 3 <enter>
  806.  
  807. ('b r' : 'R'emove breakpoint)
  808.  
  809. Now we are going to put a breakpoint just after the 'BSR' instruction :
  810.  
  811. < u StartProgram <enter>
  812. > StartProgr6100 000C                     BSR      Long
  813. > 07EADCC4: 7000                          MOVEQ.L  #0,D0
  814. > 07EADCC6: 6100 0018                     BSR      recur
  815. > 07EADCCA: 7000                          MOVEQ.L  #0,D0
  816. > 07EADCCC: 4E75                          RTS
  817. > Long      7000                          MOVEQ.L  #0,D0
  818. > 07EADCD0: 7201                          MOVEQ.L  #1,D1
  819. > 07EADCD2: 4AFC                          MOVEQ.L  #2,D2  >1
  820. > 07EADCD4: 7603                          MOVEQ.L  #3,D3
  821. > 07EADCD6: 7804                          MOVEQ.L  #4,D4
  822. > 07EADCD8: 7A05                          MOVEQ.L  #5,D5
  823. > 07EADCDA: 7C06                          MOVEQ.L  #6,D6
  824. > 07EADCDC: 7E07                          MOVEQ.L  #7,D7
  825. > 07EADCDE: 4E75                          RTS
  826. > recur     5280                          ADDQ.L   #1,D0
  827. > 07EADCE2: 0C80 0000 00C8                CMPI.L   #$C8,D0
  828. > 07EADCE8: 6E02                          BGT      theend
  829. > 07EADCEA: 61F4                          BSR      recur
  830. > theend    4E75                          RTS
  831. > 07EADCEE: 0000 07EA                     ORI.B    #$EA,D0
  832.  
  833. We see that there is still another breakpoint present in the 'Long'
  834. subroutine. Remove it with :
  835.  
  836. < b r 1 <enter>
  837.  
  838. We make the new breakpoint :
  839.  
  840. < b n 07EADCCA <enter>
  841. > 00000001,1
  842.  
  843. Now we execute until we reach that breakpoint :
  844.  
  845. < tr g <enter>
  846. > Breakpoint...
  847.  
  848. And we start all over again by setting the programcounter back to the
  849. start of the program :
  850.  
  851. < @pc=StartProgram <enter>
  852.  
  853. Now we are ready to demonstrate yet another powerful feature which looks a
  854. bit like conditional breakpoints : ²conditional tracing.
  855.  
  856. < tr c @d0==100 <enter>
  857.  
  858. ('tr c' : 'C'onditional tracing)
  859. 'tr c' singlesteps the program until the condition is true. The difference
  860. with the conditional breakpoint is that the breakpoint only checks the
  861. condition when the breakpoint is passed. With conditional tracing the
  862. condition is checked after each instruction. Conditional tracing is ofcourse
  863. much slower.
  864.  
  865. Remove the debug task from memory with :
  866.  
  867. < debug r <enter>
  868.  
  869. This command removes all breakpoints and lets the program continue. Note that
  870. you should not use 'debug r' when the program will go berserk after
  871. continuation. Use 'debug f' instead. This command ³freezes the task.
  872.  
  873. Close the debug logical window with :
  874.  
  875. < dwin <enter>
  876.  
  877.  
  878. =============================== Some theory ==================================
  879.  
  880. When you issue a trace command to PowerVisor, the 'trace' command will return
  881. immediatelly. This means that when the trace could take a long time, you will
  882. still be able to use PowerVisor for other commands. For example, when you are
  883. tracing conditionally, PowerVisor will do absolutely nothing. The debug task
  884. does everything until the condition becomes true. The debug task will then
  885. send a signal to PowerVisor and PowerVisor will update the debug display.
  886.  
  887. The conditional trace command is one of the trace commands that uses
  888. ²singlestep mode for tracing. This is slow but sometimes the only way to
  889. trace something. The 'go' trace command ('tr g') is another trace command.
  890. This trace command uses ²execute mode for tracing. The task runs at full
  891. speed until a breakpoint is encountered. It is possible that you want
  892. singlestep mode for the 'tr g' command too. For example, you could use this
  893. to see how a program runs. Since the program runs a bit slower you will be
  894. able to see much better what happens at each step. To use singlestep mode
  895. with the 'tr g' command you must use 'tr gt' ('t' for trace). Most tracing
  896. commands have these two versions.
  897.  
  898. Note that you can ³interrupt the tracing if you like with 'tr h' or
  899. 'tr f'.
  900.  
  901. Some commands (like 'tr u' and 'tr o' (explained later)) make a private
  902. breakpoint. A ²private breakpoint is a breakpoint with number 0. This
  903. breakpoint is automatically cleared when another breakpoint with number 0
  904. is about to be created.
  905.  
  906.  
  907. ========================== Resident breakpoints ==============================
  908.  
  909. You can set ²²resident breakpoints in your programs by including an 'ILLEGAL'
  910. instruction at the right place. When you want to use them you must make sure
  911. that PowerVisor is started and that you use 'mode patch'. Otherwise the
  912. results will not be very satisfactory. After that you simply start your
  913. program (from the 'Shell' or 'Workbench') (Note ! Don't use 'debug n'
  914. in PowerVisor). When the program collides with the resident breakpoint,
  915. PowerVisor will ³trap the crash. You have now made a ²crash node. You can
  916. than use 'debug t' with the crash node or with the crashed task to
  917. start debugging at the 'ILLEGAL' instruction.
  918.  
  919.  
  920. =========================== The fdebug command ===============================
  921.  
  922. To make life easier s/PowerVisor-startup defines an alias that you can
  923. use to initialize the fullscreen debugger. This alias uses the 'db'
  924. script to open the debug logical window and to initialize some
  925. keys. See the 'Aliases' reference file for more information about the
  926. 'fdebug' alias.
  927.  
  928.  
  929. =========================== The other commands ===============================
  930.  
  931. Here follows a summary of what you can do with all debug commands :
  932.  
  933.    break n <address>    Set 'N'ormal breakpoint.
  934.                         The breakpoint is not removed after breaking
  935.    break t <address>    Set 'T'emporary breakpoint.
  936.                         The breakpoint is removed after breaking
  937.    break p <address>    Set 'P'rofile breakpoint
  938.                         This breakpoint never breaks. It only increments
  939.                         the usagecounter. You can use it to see if a
  940.                         certain routine is much used
  941.    break a <address> <timeout>
  942.                         Break 'A'fter <timeout> passes.
  943.                         The breakpoint is removed after breaking
  944.    break c <address> <condition>
  945.                         'C'onditional breakpoint. This breakpoint breaks when
  946.                         the condition is true. The breakpoint is not removed
  947.                         after breaking
  948.    break r <breakpoint number>
  949.                         Remove a breakpoint
  950.    debug n              Wait for 'N'ext prorgram
  951.    debug l <filename>   'L'oad a program and load symbols
  952.    debug t <task>|<crash node>
  953.                         Take an existing task or crash node and make
  954.                         a debug node for it. With this command you can
  955.                         in theory debug any task in the system (be
  956.                         careful though)
  957.    debug f              Remove the current debug node and freeze the
  958.                         debug task
  959.    debug f <debug node> Remove the specified debug node and freeze the
  960.                         corresponding task. Use this command if you are
  961.                         debugging multiple programs at the same time.
  962.                         You can find all debug nodes in the 'dbug' list
  963.    debug r              Remove the current debug node. The debug task
  964.                         will continue executing at the programcounter
  965.    debug r <debug node> Remove the specified debug node
  966.    debug d <name>       Create a ³dummy debug node with name <name>.
  967.                         You can't use this node for debugging but you
  968.                         can use it to create ¹symbols
  969.    drefresh             Refresh the ²debug display
  970.    dscroll <offset>     Scroll <offset> bytes up in the fullscreen debugger.
  971.                         Negative values are allowed. <offset> will be made
  972.                         a multiple of two.
  973.    dstart <address>     Set the start of the debug logical window.
  974.    duse <debug node>    Set the default debug node. This is useful when
  975.                         you are debugging multiple tasks at the same time.
  976.    dwin                 Open/Close 'Debug' logical window
  977.    symbol l <filename> [<hunkaddress>]
  978.                         ³Load the symbols for the current debug task.
  979.                         If you give <hunkaddress>, PowerVisor will load the
  980.                         symbols for the given ¹hunks. This is extremely
  981.                         useful when you have created a ³dummy debug task.
  982.                         Note that <hunkaddress> is 4 more than the number
  983.                         given in the hunklist with the 'hunks' command.
  984.                         Note that <hunkaddress> is not optional when you are
  985.                         loading symbols for a dummy debug task.
  986.    symbol c             Clear all symbols for the current debug node
  987.    symbol a <symbolname> <value>
  988.                         Add a symbol to the list of symbols
  989.    symbol r <symbolname>
  990.                         Remove a symbol from the list of symbols
  991.    symbol s             List all symbols for the current debug node
  992.    trace                Trace one instruction (singlestep mode)
  993.    trace n <number>     Trace <number> instructions (singlestep mode)
  994.    trace b              Trace until the next change of program flow
  995.                         (singlestep mode)
  996.    trace t              Trace over JSR or BSR. IF the instruction is
  997.                         not a BSR or JSR this command is analogous to
  998.                         'trace' (execute mode)
  999.    trace j              Trace until a library ROM function is about
  1000.                         to be called with JMP ...(a6) or JSR ...(a6).
  1001.                         (singlestep mode)
  1002.    trace r <register>   Trace until a specified register is changed.
  1003.                         Register can be d0-d7, a0-a6 or sp.
  1004.                         (singlestep mode)
  1005.    trace u <address>    Trace until programcounter is equal to <address>.
  1006.                         This command works by setting a private
  1007.                         breakpoint (number 0) at <address>. This command
  1008.                         only works when <address> is not in ROM
  1009.                         (execute mode)
  1010.    trace ut <address>   Trace until programcounter is equal to <address>.
  1011.                         No breakpoint is set by this command. <address>
  1012.                         can be in ROM
  1013.                         (singlestep mode)
  1014.    trace o              Trace over the current instruction. This command
  1015.                         is analogous to 'trace u' with <address> equal
  1016.                         to the instruction following the current instruction
  1017.                         (execute mode)
  1018.    trace ot             Trace over the current instruction.
  1019.                         This version can be used in ROM
  1020.                         (singlestep mode)
  1021.    trace c <condition>  Trace until <condition> is true
  1022.                         (singlestep mode)
  1023.    trace s              Skip instruction
  1024.    trace i              Do not trace. Show the current registers and
  1025.                         instructions (obsolete in the fullscreen debugger)
  1026.    trace g              Trace until a breakpoint is encountered (note that
  1027.                         all previous trace commands also stop when a
  1028.                         breakpoint is encountered)
  1029.                         (execute mode)
  1030.    trace gt             Trace until a breakpoint is encountered
  1031.                         (singlestep mode)
  1032.    trace h              Interrupt the tracing or executing of the
  1033.                         current debug task
  1034.    trace f              Interrupt the tracing or executing of the
  1035.                         current debug task as soon as this task
  1036.                         is in ready state
  1037.    with <debug node> <command>
  1038.                         Temporarily set the current debug node and execute
  1039.                         <command>. This is useful for example, if you are
  1040.                         debugging with multiple programs at the same time and
  1041.                         you want to have a look at the symbols or registers
  1042.                         of the other program
  1043.  
  1044.